MacSilverWare/macsilverware.iso/Education/Bugglings/Buggling Docs.text

Text File | 1989-05-19 | 18KB | 413 lines

Bugglings 1.0, by Chuck Shotton
===============================

(Note: This documentation looks best if printed using Monaco 9 pt,
       with tabs every 3 spaces)

(Another Note: This is a reasonably complicated program. You'll get
       more out of it if you carefully study the documentation prior
             to running Bugglings.)

============
Introduction
============
If you ever wanted to be the master of your own universe, here's the
program for you...

Bugglings is a program based on the Computer Recreations column in the
May 1989 issue of Scientific American. This program simulates life in
a test tube, with tiny bugs swimming around, feeding on food particles.

The bugs are driven by a set of 9 genes that determine how
they swim about in the test tube. As the bugs feed on food particles,
grow fat and fission into new bugs. When this happens, the two new bugs
retain most of the genetic features of the parent bug, but one of them
is slightly mutated.

Through the course of several generations, bugs will evolve survival
traits based on their environment. Some bugs will "learn" where food
shows up, moving in those areas only. Some evolve into bugs that can
rapidly cover large distances, searching for food. Others will evolve
into carnivores that feed on their weaker neighbors. You can affect
the evolution of your bugs by modifying their environment while the
simulation is running.

===================
Running the Program
===================
The Stuffit archive contains two versions of the Bugglings program. The
version titled "Bugglings" should run on any Macintosh that has 512k to
spare (I'm not sure if it'll run on 512k Macs or not). The program
titled "Bugglings '020+" will only work on Macs with a 68020 or greater
and a math coprocessor. Other than the different processor requirements,
both programs are identical, including support for color. Bugglings is
compatible with Multifinder, and will run simulations in the background.

To get started, simply run the appropriate version of Bugglings for your
Mac. For monochrome display users, double-clicking on the "Black & White
Startup" document will bring Bugglings up already configured for your
display.

=============
The Test Tube
=============
The main window that opens up represents the test tube you will be
experimenting in. The screen is arranged in a rectangular matrix that
can vary in size from 8 by 15 cells to 275 by 500 cells. Each location
on the screen can contain a food particle, a bug, a piece of the test
tube wall, or can be empty. Bugs are represented by solid (black, white,
or colored) boxes, while food is represented by grey boxes.

The bottom of the main window contains two rectangular boxes. The box on
the lower left will display the number of generations (cycles) that
have elapsed in the simulation, as well as the current living population
total in the test tube. The wider box in the lower right of the screen
is the status box, and will be used to display information about a
specific bug.

========
The Bugs
========
As mentioned, the bugs have 9 genes that control their behavior. 8 of
the genes control the bugs' motion, while the 9th controls how
carnivorous a bug is. In addition to these genes, all bugs have
attributes that control:
• How old they must be before they can breed.
• How much energy (food) they must have in order to breed.
• How much energy (food) they can hold at one time. (stomach size?)
• How weak they can be before they die.
• Who their parent was.

During each cycle, a bug may turn and move in one of eight directions as
shown below:

          Forward
      Left   |   Right
           \ | /
Med. Left----+----Med. Right
           / | \
  Hard Left  |  Hard Right
            Reverse

The direction of motion is relative to the direction a bug is facing. If
a bug is facing the right side of the screen and decides to move to the
right (Med. Right), the bug will appear to move towards the bottom of
the screen. The bug's new facing direction would then become towards the
bottom of the screen, and subsequent moves would be relative to that
facing.

Each move costs a bug 1 point of energy. When a bug moves across a food
particle, it is eaten. If the bug's total energy is below its maximum,
the the energy value of the food particle is added to the bug's total
energy. If a bug eats another bug, its energy is increased by the amount
of energy the eaten bug had. If a bug's energy level falls to 0, it will
be unable to move.

The Genes
---------
The eight movement genes determine the probability that a bug will turn
and move in a given direction. The first gene listed is a bug's tendency
to move straight ahead. The second is its tendency to make right turns,
and so forth (clockwise around the diagram above, ending with the 8th
gene controlling left turns.) If a bug had the following genes:
10,5,0,0,5,0,0,0
its movement is computed as follows.The value of all genes is totaled up.
In this case the total value of all genes is 20. The probability that a bug
will turn and move in any direction is computed by dividing the value of
a single gene by the total. In this case, the bug will move forward 50% of
the time (10/20) and will go to the right or in reverse 25% of the time
respectively. A random number is chosen, and according to the distribution
of probabilities, the appropriate direction for the bug is chosen.

The 9th gene controls a bug's taste for flesh. If the Carnivore gene falls
below a user-specified level, the bug will only eat food particles. If the
gene is above another level, the bug will only eat other bugs. If it falls
in the range between these two levels, it represents the probability that
a bug will choose to eat food or other bugs. The higher the gene's value,
the less herbivorous the bug and vice versa. Bugs will only feed on other
bugs with a lower Carnivore gene, so this gene also represents how
physically strong a bug is.

Breeding
--------
A bug will breed provided it is old enough and has enough energy stored up.
When a bug breeds, its offspring have a chance of having mutated genes. It
is through this mutation process that new bugs evolve. Also, you have the
option of introducing radiation into the environment which will cause
mutations in bugs at any time, not just when breeding.

Breeding is by fission. When this occurs, both new bugs will have half
of the energy of the original bug, and their age will be reset to zero.
Also, the new bug will have some of its genes mutated. The original bug,
now half its original size, will remain untouched genetically. There is
a limit of 1000 bugs total in the simulation at any one time.

==========
The Cursor
==========
You will notice that the cursor changes from the usual arrow to a set of
crosshairs when the mouse enters the test tube area of the main screen.
By positioning the cursor over a bug while the simulation is running (or
paused) and clicking, the stats of a particular bug will be shown in the
status box. If you hold down the shift key and click on a bug, that bug
will be destroyed and removed from the test tube.

==============
The Status Box
==============
The status box will show the stats for whatever bug is currently selected
using the cursor as described above. If that bug dies, the display will
show no bug. A sample display in the status box might contain:

#22(5):M=90 E=390 D=6 Genes: 0,5,0,2,0,3,2,1,3

The fields are interpreted as follows:

#22(5) - This indicates that the bug being observed is #22, and it belongs
to the family of bugs whose original parent was bug 5. For users with
color displays, all bugs of the same family have the same color. If there
are more than 7 bugs initially, then some colors will be used by more than
one family.

M=90 - This shows that the bug has moved 90 times, or is 90 cycles old.

E=390 - This is the bug's current energy level.

D=6 - This is absolute direction that a bug is facing. In this case, 6
indicates that the bug is facing to the left of the screen. (0 is up,
2 is right, etc.)

Genes: - These nine numbers are the nine genes associated with each bug.
The first number is the Forward gene, followed by the Right gene, etc. The
last gene is the Carnivore gene.

Tracking Bugs
-------------
When you are tracking a bug, it is often difficult to pick your bug out
of a crowd. By clicking the mouse in the Status Box, all motion on the
screen will stop, and the currently selected bug will flash briefly.

=========
The Menus
=========
Bugglings only has three menus. The FILE menu is used to load or save
the current configuration of the test tube and bugs. EDIT menu options
are only functional when used with desk accessories. The SIMULATION menu
contains all of the controls that are used to run and modify the
simulation.

FILE
----
The Open command is used to load a settings file. These files contain
saved values for all of the information provided in the Environment, Bug,
and Test Tube settings dialogs.

The Save As command will save the current values of the information in the
Environment, Bug, and Test Tube settings dialogs.

Quit will exit the program immediately. Clicking in the go-away box of the
main window has the same effect.

EDIT
----
As mentioned, options in the Edit menu are supplied for the convenience of
Desc Accessories running under the regular Finder.

SIMULATION
----------
The Run, Pause, and Stop commands are used to control the execution of a
simulation. When Run is selected, a new simulation is started, using the
current settings from the various dialogs.

Pause will cause the currently executing simulation to halt. This makes it
easier to select bugs for tracking, change environment settings, or get
a sandwich. Selecting Pause again will resume the current simulation.

Stop will terminate the simulation, leaving the screen undisturbed. If
the population reaches zero during any simulation, the simulation will
automatically stop.

The Environment, Bug, and Test Tube Settings options bring up dialogs for
controlling the simulation. These dialogs are described in more detail
below.

The Change Colors option will temporarily invert the display. This option
can be used to determine which background color (white or black) is more
appealing. For black and white displays, it is suggested that a white
background always be used, since most bugs will appear black.

================
Settings Dialogs
================

Each field in the following dialogs is described. At the end of the
description is the legal range of values for that field.

Environement Settings
---------------------
The Environment Settings Dialog is the most important dialog box. This
dialog can be used to change the parameters of a simulation before it is
started, or while the simulation is executing. This allows you to increase
the food being added to the environment, for example, while the
simulation is running.

*** IMPORTANT NOTE ***
Any changes to the Environment Settings will NOT take effect until you
click on the OK button, or press return. This allows you to change many
parameters at once while the simulation is running. If you decide you
don't want to change the values, clicking on cancel will revert to
the currently active values. If the value is out of range, the previous
correct value will be supplied.

The fields in the Environment Settings dialog are defined as follows:

Radiation Level : This is a number between 0 and 100 that represents the
percentage chance that one bug will be mutated during any cycle. The bug
is chosen at random, as are the genes.

Herbivore Level : If a bug's Carnivore gene falls below this level, the
bug will only eat food particles. Set it very  high if you want all
bugs to be herbivores. 0-32767

Carnivore Level : If a bug's Carnivore gene is above this value, the bug
will only feed on other bugs. Again, set this very high (and higher than
the Herbivore Level) if you want only Herbivores. 0-32767

Food Value : When a bug eats a food particle, it will gain this much
energy. 0-32767

Food Density : This field describes how dense food will be distributed
when the simulation starts. It is specified as a 1 in N+1 chance that a
given cell will contain a food particle. If the value is 3, there will
be food in 25% of the cells when the simulation starts. 1-1000

Feeding Frequency : This represents a percentage of cycles in which food
will be added to the test tube. If it is 75, food will be added to the
simulation 75% of the time (3 cycles out of 4). 0-100

Feeding Amount : When it's feeding time, this is how may food particles
will be randomly placed in the test tube. (If an attempt is made to place
a particle on an occupied cell, the particle is discarded.) 0-32767

Full Energy Level: This is the maximum amount of energy a bug can hold.
It's analogous to the bug's stomach size. 0-32767

Death Level : If a bug's energy level falls below this value, a bug will
die and be removed from the simulation. -32768-32767

Breeding Age : A bug must survive this many cycles or generations before
it is allowed to breed. 0-32767

Breeding Energy : A bug must possess this much energy in order to fission.
Set this value above the Full Energy level to inhibit breeding. 0-32767

Bug Settings
------------
This dialog can only be invoked prior to running a simulation. The fields
are defined as follows:

Initial Bug Count : This represents how many bugs will be present
in the test tube when the simulation starts. 1-1000

Initial Energy : All of the initial bugs will start with this much energy.
0-32767

Initial Genes : This determines the highest value for any gene in the
initial bugs. Gene values will range from 0 to this value. The higher the
value, the less impact mutations will have on the genes. Once the
simulation is running, the bugs' gene values may range from 0 to 2 times
this value. 0-50

# Genes to Mutate : When a bug's genes mutate, due to radiation or
breeding, this value determines how many genes are affected. 0-9

Mutation Delta : When a gene is mutated this value is used to determine
the amount of mutation. A gene will be changed by a random amount
between -N and N. 0-50

Bug #1 is Special : This check box really doesn't do anything.

Looper : This check box, when selected, will initialize bug #1's
movement genes to 10,5,0,0,0,0,0,0, causing it to make large clockwise
loops across the screen.

Carnivore : When this check box is selected, bug #1's Carnivore gene will
be set high enough to insure that it will be a pure carnivore.

Test Tube Settings
------------------
This dialog can only be invoked prior to running a simulation. It controls
many of the parameters associated with the size and appearance of the
display. Fields are as follows:

Garden of Eden : As described in the Scientific American article, this
check box will cause food to be replenished at twice the normal rate in
an area in the upper left corner of the screen.

Wrap-around Universe : When checked, this option will cause bugs that move
off the edge of the screen to reappear on the opposite edge. Turning it off
will draw a wall around the screen that the bugs will bang into.

Use White Background : This option is useful for monochrome displays. It
causes the background to be white instead of the default black. The
bugs will then show up as black rectangles.

Cell Width : This determines how wide cells on the screen will be. The
larger the width, the fewer horizontal cells available. 1-32

Cell Height : Same as above, but determines the vertical size of the cells.
Width and Height need not be the same value. 1-32

===============
Hints and Stuff
===============
Bugglings is a fairly complicated program. You can simulate lots of
natural population phenomena, ranging from locust plagues to coyote
and rabbit population cycles. Of course, it's all in your interpretation
of the behavior in the test tube.

The program tends to bog down when the populations get very high. It's
possible to limit population size by adjusting things like the Full
Energy Level and Food Value (aside from the obvious parameters like
Breeding Age and Energy). The evolution of well-adapted bugs seems to
work best with high turn-over in population initially, and then making
the population more stable later. Do this by raising the breeding age and
energy while the simulation is running.

======================================
ShareWare, Source Code, Licenses, etc.
======================================

Bugglings was written by Chuck Shotton in Think Pascal. The program is
copyrighted 1989 by Chuck Shotton and BIAP Systems. Portions of the
program are Copyrighted by Think, Inc.

If you find Bugglings to be a useful or interesting program, please
consider paying the $5 ShareWare fee. This gives me incentive to write
more goodies like this one. If you are truly interested in the inner
workings of this program, or would like to make your own modifications,
Think (Lightspeed) Pascal source code is available for $8. The source
should also be an easy port to other Mac Pascal compilers.

Limited license is granted for your own personal use of this software.
If you are considering bundling this software with other packages, adding
it to a commercial shareware anthology, or using it in a commercial,
government, or educational environment, please contact the author regarding
special licensing agreements.

Thanks,

Chuck Shotton
c/o BIAP Systems
P.O. Box 580622
Houston, TX 77258-0622

Genie: C.SHOTTON12
Compu$erve: 72460,764
AppleLink: D1683

BIAP BBS: [phone], 1200-8-N-1